@thallylabs/migrate 0.2.39 → 0.2.41

package/README.md

@@ -21,6 +21,36 @@ an explicit `scopePath` remains authoritative. Deep article seeds do not widen a
 mounted documentation tree to its marketing origin. Mintlify configuration page
 IDs resolve against that mount, while ordinary HTML links keep URL semantics.
 
+Query strings remain part of page identity. A query URL becomes an article alias
+only after independent captures prove identical article, metadata, deferred source
+and alternative-state content. A section query must name an observed anchor;
+query-selected versions, locales and different articles remain separate pages.
+The alias keeps its own capture evidence and checked section destination.
+
+Self-contained inline SVGs become passive, hash-addressed assets. An optional
+trusted `rasterizeSvg` host callback can replace rejected SVG with bounded PNG;
+the engine still checks PNG MIME/signature and records the original SVG digest.
+It never relaxes the SVG allowlist or supplies a browser. Hosts must enforce an
+isolated, credential-free renderer with no network or page JavaScript.
+
+Complete ARIA-linked tab panels preserve labels and source order, including
+surrounding authored content. For known embedded article-source contracts, literal
+missing code panels and explicit languages may be recovered only when the source
+is referenced by the article and matches its headings, prose, visible examples
+and tab labels. Embedded imports and expressions never execute. Unreferenced,
+conflicting, incomplete or unsupported alternatives remain review blockers.
+
+The Fumadocs adapter reads bounded JSON-only React Flight frames reachable from
+the response's root record. It supports article-owned copy-source references and
+literal `Tabs`/`Tab`/`Accordion` children, including loaded disclosure prose,
+examples, tables and theme-specific images. It renders a fixed set of static
+elements; unknown components, executable markup and unresolved references keep
+their review requirement. Languages come only from explicit source declarations;
+examples without that metadata remain unlabeled. Source heading IDs and known
+Shiki display annotations are recognized for matching while captured code stays
+unchanged. A capture provider can supply complete rendered alternatives when a
+publisher does not expose a supported inert data contract.
+
 The returned `checkpoint` is JSON-safe. `onRecord` lets a host persist a completed
 page before acknowledging it; `onCheckpoint` emits bounded deltas, including
 pending discoveries and checkpoint identity fields. Merge delta records by URL,
@@ -42,8 +72,19 @@ Responsive `picture`/`source`/`img` choices retain their descriptors, media
 conditions, sizing and literal alt text. Every candidate is localized; shared
 asset URLs are fetched once and identical payloads count once toward the byte
 budget, including resumed journals. Complete static tab panels are preserved as
-alternatives; empty/lazy panels still require a capture provider. Complete local
-OpenAPI operations can represent deferred API schemas. Supported native video
+alternatives; empty/lazy panels without verified embedded source still require a capture provider. Complete local
+OpenAPI operations can represent only their exact deferred API fields. A known
+client-rendered request-example contract may use that registered operation to
+regenerate standard language examples; the inline and sidebar slots must be uniquely owned and
+captured panels must be complete. For the supported legacy selected-example
+component, the selected source, title and language must agree with the exact
+root-owned provider inventory. Every authored alternative, including inactive
+same-language examples, is retained byte for byte in the registered specification
+and rendered by the runtime generator. An unmatched or missing inventory remains
+a review blocker. Ordinary language
+pickers and ambiguous or unknown slots still require review. Every captured
+response, including alternative states, receives the same completeness checks;
+the presence of an unrelated state does not excuse a missing panel. Supported native video
 and YouTube embeds retain their original public media URLs, recorded in source
 warnings; videos are not downloaded. A trusted host may report an original asset
 as already absent (HTTP 404/410): its absolute source URL and a warning are
@@ -58,7 +99,7 @@ Missing primary counterparts and projected path collisions require review; the
 engine does not invent translations. Fresh HTML captures also observe `html lang`; conflicting or unsupported
 language evidence requires review. Capture adapters can supply `locale` when
 no language is declared in HTML or identified by the scoped URL path.
-The `url-evidence-v5` converter rejects earlier journals: replay retained raw
+The `url-evidence-v6` converter rejects earlier journals: replay retained raw
 captures into a new journal rather than relabelling previously hashed pages.
 
 `stopReason` distinguishes a resumable `capture-limit` from hard `page-limit`
@@ -107,7 +148,8 @@ renderer, so it always produces a clear warning naming the spec instead of
 disappearing.
 
 `METHOD /path` entries (`"POST /v2/keys.createKey"`) under a container that
-binds an `openapi` spec become `api.groups` on the tab that spec binds to:
+binds an `openapi` spec become pages of the site (see the next paragraph) or,
+where that is not possible, `api.groups` on the tab that spec binds to:
 nested groups, icons and authored order are kept, and page entries stay in the
 tab's own groups (a group that mixes pages and operations is split, so the
 sidebar lists the API groups after the page groups). Operations written
@@ -137,8 +179,55 @@ site imported by URL, cannot be placed: one warning says they were not added to
 operations still have their pages. This is separate from a `directory`'s flat
 operation list, which still only drives the endpoint redirects.
 
+Mintlify serves one generated page per operation a navigation container lists,
+at `/<directory>/<first tag>/<summary>` (`directory` is the reference's
+`{ source, directory }` folder, `api-reference` when it is a plain string).
+Each such operation becomes an MDX page at that path under `src/content`, so it
+keeps its URL, sidebar entry, eyebrow and previous/next links. Its frontmatter is
+the summary as `title` (else the operation id, else `METHOD /path`), the first
+sentence of the description as `description` (the title when there is none), and
+`openapi: "<spec file> METHOD /path"`; the body is empty. `descriptionPlacement: operation`
+keeps that short summary for search and metadata while the runtime renders the
+full operation description as Markdown, including every paragraph and warning.
+The tab that listed the
+operations is an ordinary page tab, kept where it was among its siblings and
+labelled as they are (`Product: API reference`), whose groups are the authored
+ones, nesting and order kept, each operation replaced by its page. Tabs that were
+separate in the source are never merged, even when they share a spec. The spec
+is bound once per spec file in a hidden tab (`OpenAPI: <spec>`, the same as for a
+spec only a page names), which is what the pages' `openapi:` frontmatter resolves
+against; the renderer serves no `/api/` page, sitemap entry or search record for it. A remote spec's pages
+and tab are made by `hydrateRemoteApiSpecs` once it is downloaded; a download
+that fails leaves no tab and no page, as before. An operation the spec withholds
+(`x-hidden`, `x-excluded`) gets no page, nor does one listed only under a
+`hidden` group or an access-restricted container (such groups are left out of
+the tab, as above). Of two operations with the same tag and
+summary the first listed keeps the URL and one warning names the others; an
+authored page at that URL keeps it. Nothing is redirected from these URLs and a
+link to one stays as written; a link to a tag folder or to an address under the
+directory that matches no page goes to a page, and a folder of pages with no page
+of its own opens on its first page, as in any other navigation. The operations
+fall back to `api.groups` on an API tab, as described above, when the containers
+that share a tab disagree on the directory, the directory cannot be a folder name,
+the spec has none of the listed operations, or the tab is bound to another spec.
+A reference that lists no operation (Mintlify generated every endpoint) is not
+affected. Operations whose path item is a local `$ref` are read as the renderer
+reads them (hidden or excluded on any level of the reference withholds them).
+The renderer tries the first visible API tab's spec first for a bare
+`openapi: "METHOD /path"` page; when converting a tab to pages stops its spec being
+that one, each bare reference to an operation the converted spec defines is
+written with that spec's path in front, so it still renders the same operation.
+
 Mintlify `styling.eyebrows: "breadcrumbs"` becomes `eyebrow: "path"` (the full
 group path above the page title); `"section"` or no setting writes nothing.
+Mintlify sources also get `smartQuotes: true`, because Mintlify renders straight
+quotes in prose as curly ones; the setting leaves code, heading ids, Markdown and
+`llms.txt` as written.
+
+Thally leaves out the sidebar heading of a group named after its tab or dropdown, because
+the collection already names it. Mintlify keeps that heading, so a source with such a group
+(an `API reference` dropdown whose first group is also `API reference`) gets
+`navigation.groupHeadings: "all"`. A source without one gets nothing.
 
 Page `openapi:` frontmatter with a spec prefix
 (`openapi: "specs/openapi-b.yaml GET /widgets/{id}"`) is rewritten to where the
@@ -158,7 +247,8 @@ no operation points to that section's overview page instead, and one warning
 lists the affected links (up to ten). A link to an address the site answers
 itself (a guide authored inside an API directory, trailing slash or `/index` or
 not, or the source of an authored redirect) is never rewritten. A spec that
-Mintlify mounted under a `directory` also gets a redirect from each endpoint URL that directory served,
+Mintlify mounted under a `directory` also gets a redirect from each endpoint URL that directory served
+(not the operations a container lists, which are pages at those URLs),
 to the matching endpoint page, and never to an operation the published spec
 withholds with `x-hidden` or `x-excluded`. A remote spec gets every directory
 each of its tabs mounted it under, limited to the operations the navigation
@@ -203,6 +293,15 @@ whose address has a `+ ? ( ) [ ] { }` character (a `directory` such as
 spec or a downloaded spec is left out instead, and one warning lists the first
 ten of them.
 
+A Mintlify page whose frontmatter `url` is a web address is a link in the
+source sidebar. It is imported as a page that is kept out of the sitemap, stays
+in the navigation, and has a redirect from its path to that address. That
+redirect is added after the checks above, because hiding the page is its
+purpose; a `url` that is not an `http(s)` address is ignored. The home page
+(`index.mdx` or `introduction.mdx`) is served at `/` and at `/introduction`, so
+both redirect, and the redirect from `/` replaces the generated one to the first
+page. A redirect for `/` that the source site wrote stays, and a warning says so.
+
 A repository is limited to 5,000 documentation files and, separately, 5,000
 asset files. Past that, files are kept in navigation order with the default
 version first, then pages not listed in navigation, and one warning counts and

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { M as MigrationPage, a as MigrationAsset, b as MigrationNavigationGroup, R as RenderedMigrationFile, c as MigrationWarning, d as MigrationFetcher, e as MigrationPlatform, f as MigrationBundle, g as MigrationDocsConfig } from './url-run-BOZvcGs1.js';
-export { h as MigrationCapture, i as MigrationCaptureProvider, j as MigrationCaptureState, k as MigrationCapturedAsset, l as MigrationEvidence, m as MigrationFetchRequest, n as MigrationFetchResponse, o as MigrationJournalAsset, p as MigrationNavigationOccurrence, q as MigrationNavigationTab, U as UrlMigrationCheckpoint, r as UrlMigrationCheckpointDelta, s as UrlMigrationIssue, t as UrlMigrationRecord, u as UrlMigrationRun, v as UrlMigrationRunOptions, w as UrlMigrationValidation, x as classifyMigrationResponse, y as mergeMigrationConfig, z as renderMigrationFiles, A as runUrlMigration, B as validateUrlMigration } from './url-run-BOZvcGs1.js';
+import { M as MigrationPage, a as MigrationAsset, b as MigrationNavigationGroup, R as RenderedMigrationFile, c as MigrationWarning, d as MigrationFetcher, e as MigrationPlatform, f as MigrationBundle, g as MigrationDocsConfig, E as EndpointTabSlot } from './url-run-mSKFqHx_.js';
+export { h as MigrationCapture, i as MigrationCaptureProvider, j as MigrationCaptureState, k as MigrationCapturedAsset, l as MigrationEvidence, m as MigrationFetchRequest, n as MigrationFetchResponse, o as MigrationJournalAsset, p as MigrationNavigationOccurrence, q as MigrationNavigationTab, U as UrlMigrationCheckpoint, r as UrlMigrationCheckpointDelta, s as UrlMigrationIssue, t as UrlMigrationRecord, u as UrlMigrationRun, v as UrlMigrationRunOptions, w as UrlMigrationValidation, x as classifyMigrationResponse, y as mergeMigrationConfig, z as renderMigrationFiles, A as runUrlMigration, B as validateUrlMigration } from './url-run-mSKFqHx_.js';
 export { isPassiveSvg } from './svg-policy.js';
 
 /**
@@ -171,6 +171,14 @@ interface MintlifyNavigationResult {
     referenceAccess: Array<MintlifyReferenceAccess>;
     /** `sourceRef` mounts under a restricted container; never resolved, so nothing of theirs is imported. */
     gatedSourceRefs: Array<string>;
+    /**
+     * The API tabs that list operations and nothing else, which `docsConfig.tabs` leaves out: each with the navigation container that
+     * owns it and the place it held among the tabs. Only produced with `operationGroups`; the spec binding puts such a tab back as a page tab.
+     */
+    apiTabSlots: Array<{
+        container: object;
+        slot: EndpointTabSlot;
+    }>;
     warnings: Array<MigrationWarning>;
 }
 interface MintlifyProjectionOptions {